DragonFly On-Line Manual Pages
frame(l) BEGEMOT Library frame(l)
NAME
frame - simple message protocol for byte streams
SYNOPSIS
# include <begemot.h>
int frame_write(int fd, void *hdr, u_int hdr_len,
void *arg...)
int frame_writev(int fd, void *hdr, u_int hdr_len,
struct iovec *vec, u_int veclen)
int frame_read(int fd, void *hdr, u_int hdr_len,
void **parg, u_int *plen)
int framefd_write(int fd, void *hdr, u_int hdr_len,
void *arg...)
int framefd_writev(int fd, void *hdr, u_int hdr_len,
struct iovec *vec, u_int veclen)
int frame_read(int fd, void *hdr, u_int hdr_len,
void **parg, u_int *plen)
DESCRIPTION
Most reliable protocols available on UNIX systems are byte stream
protocols. On the other hand there are many cases, where you need to
transfer messages. A simple way to do this is to prepend the message
length to the message and transfer it on the byte stream. The frame_*
functions are designed to simplify this task for most cases. They
assume, that you want to transfer messages, which consist of a fixed
length header and a variable length part. The fixed header consists of
at least four bytes, which contain the variable parts length in network
byte order. For the framefd_* functions the header consists of 8 bytes:
4 bytes for the length and 4 bytes for a file descriptor. Of course,
the fixed header can be longer than this minimum.
There are two pairs of functions. The first pair frame_read and
frame_write can be used on any reliable byte stream (pipes, UNIX domain
sockets, TCP sockets, ...). The framefd_read and framefd_write
functions are specifically designed for UNIX domain sockets --
additionally to messages they allow the optional transfer of a file
descriptor with each message.
The parameter fd is the file descriptor on which the transfer should
take place. hdr is a pointer to the fixed size header, which is of
size hdr_len. hdr_len must be either 4 or 8 bytes minimum. The first
four bytes are set to the length of the variable part in the write
functions and contain the length of this part if the read functions
return. The second four bytes of the header must contain the file
descriptor or -1 for the framefd_write function. It will contain the
received file descriptor, -1 if there was no file descriptor or -2, if
the writing side indicated, that it will send a file descriptor, but
did not send one. The latter indicates an error in the protocol. A file
descriptor, that is received, but not expected is closed.
arg is the start of a variable argument list. This list should consist
of pairs of void * pointers and u_int sizes, each pair describing a
piece of the variable message part. The list must be terminated by a
NULL pointer. If no variable part is to be transmitted, the first
pointer should simply be NULL.
parg on the other hand should point to a pointer which points to a
buffer for the variable length part. The size of the buffer is
indicated by the number pointed to by plen. If the indicated buffer
size is too small for the received message's variable part it will be
reallocated by calling xrealloc(l). The actual length of the variable
part is indicated in the first four bytes of the header. This
mechanism tries to minimize buffer allocations and reallocations.
There is no need to reallocate anything once you got the biggest
message.
An example on how to use the functions can be found at the end of
frame.c.
The functions with the v suffix take a pointer to a struct iovec and an
associated length instead of a variable argument list. To use these
functions you need to
# include <sys/uio.h>
RETURN VALUES
The write functions return the return value of the corresponding system
call. Look under sendmsg(2) and writev(2).
If frame_read is unable to receive the fixed size header, or the header
is too small, it returns the value from the recvmsg(2) or readv(2)
system call. If the corresponding call for the variable part returns
an error or EOF, the system call's value is returned (0 or -1). If the
calls for both the header and the variable part are ok, the sum of the
sizes of both received parts is returned. This means, that you should
check, that the value returned from the read functions is equal to the
sum of hdr_len and the first four bytes of the header.
SEE ALSO
sendmsg(2),writev(2) recvmsg(2),readv(2)
BUGS
The FreeBSD kernel crashes, if you use framefd_write on the writing
side and frame_read on the reading side. The crash occures in so_flush
in both the 2.X and 3.0 kernels.
You cannot transfer file descriptors over pipes in FreeBSD 3.0 anymore,
because the pipe implementation is not based on socketpair(2) as it was
the case in all earlier BSDs.
Due to a bug in the Solaris 2.5 socket emulation it is not possible to
mix framefd_write with frame_read.
The write functions impose a limit on the length of the argument list
and the uio vector. This limit is defined in frame.c and is currently
defined to be 100.
AUTHOR
Hartmut Brandt, harti@freebsd.org
BEGEMOT 8 Feb 1998 frame(l)
frame(n) Tk Built-In Commands frame(n)
______________________________________________________________________________
NAME
frame - Create and manipulate 'frame' simple container widgets
SYNOPSIS
frame pathName ?options?
STANDARD OPTIONS
-borderwidth -highlightcolor -pady
-cursor -highlightthickness -relief
-highlightbackground -padx -takefocus
See the options manual entry for details on the standard options.
WIDGET-SPECIFIC OPTIONS
Command-Line Name:-background
Database Name: background
Database Class: Background
This option is the same as the standard -background option
except that its value may also be specified as an empty string.
In this case, the widget will display no background or border,
and no colors will be consumed from its colormap for its
background and border.
Command-Line Name:-class
Database Name: class
Database Class: Class
Specifies a class for the window. This class will be used when
querying the option database for the window's other options, and
it will also be used later for other purposes such as bindings.
The -class option may not be changed with the configure widget
command.
Command-Line Name:-colormap
Database Name: colormap
Database Class: Colormap
Specifies a colormap to use for the window. The value may be
either new, in which case a new colormap is created for the
window and its children, or the name of another window (which
must be on the same screen and have the same visual as
pathName), in which case the new window will use the colormap
from the specified window. If the -colormap option is not
specified, the new window uses the same colormap as its parent.
This option may not be changed with the configure widget
command.
Command-Line Name:-container
Database Name: container
Database Class: Container
The value must be a boolean. If true, it means that this window
will be used as a container in which some other application will
be embedded (for example, a Tk toplevel can be embedded using
the -use option). The window will support the appropriate
window manager protocols for things like geometry requests. The
window should not have any children of its own in this
application. This option may not be changed with the configure
widget command. Note that -borderwidth, -padx and -pady are
ignored when configured as a container since a container has no
border.
Command-Line Name:-height
Database Name: height
Database Class: Height
Specifies the desired height for the window in any of the forms
acceptable to Tk_GetPixels. If this option is less than or
equal to zero then the window will not request any size at all.
Note that this sets the total height of the frame, any
-borderwidth or similar is not added. Normally -height should
not be used if a propagating geometry manager, such as grid or
pack, is used within the frame since the geometry manager will
override the height of the frame.
Command-Line Name:-visual
Database Name: visual
Database Class: Visual
Specifies visual information for the new window in any of the
forms accepted by Tk_GetVisual. If this option is not
specified, the new window will use the same visual as its
parent. The -visual option may not be modified with the
configure widget command.
Command-Line Name:-width
Database Name: width
Database Class: Width
Specifies the desired width for the window in any of the forms
acceptable to Tk_GetPixels. If this option is less than or
equal to zero then the window will not request any size at all.
Note that this sets the total width of the frame, any
-borderwidth or similar is not added. Normally -width should
not be used if a propagating geometry manager, such as grid or
pack, is used within the frame since the geometry manager will
override the width of the frame.
______________________________________________________________________________
DESCRIPTION
The frame command creates a new window (given by the pathName argument)
and makes it into a frame widget. Additional options, described above,
may be specified on the command line or in the option database to
configure aspects of the frame such as its background color and relief.
The frame command returns the path name of the new window.
A frame is a simple widget. Its primary purpose is to act as a spacer
or container for complex window layouts. The only features of a frame
are its background color and an optional 3-D border to make the frame
appear raised or sunken.
WIDGET COMMAND
The frame command creates a new Tcl command whose name is the same as
the path name of the frame's window. This command may be used to
invoke various operations on the widget. It has the following general
form:
pathName option ?arg arg ...?
PathName is the name of the command, which is the same as the frame
widget's path name. Option and the args determine the exact behavior
of the command. The following commands are possible for frame widgets:
pathName cget option
Returns the current value of the configuration option given by
option. Option may have any of the values accepted by the frame
command.
pathName configure ?option? ?value option value ...?
Query or modify the configuration options of the widget. If no
option is specified, returns a list describing all of the
available options for pathName (see Tk_ConfigureInfo for
information on the format of this list). If option is specified
with no value, then the command returns a list describing the
one named option (this list will be identical to the
corresponding sublist of the value returned if no option is
specified). If one or more option-value pairs are specified,
then the command modifies the given widget option(s) to have the
given value(s); in this case the command returns an empty
string. Option may have any of the values accepted by the frame
command.
BINDINGS
When a new frame is created, it has no default event bindings: frames
are not intended to be interactive.
SEE ALSO
labelframe(n), toplevel(n), ttk::frame(n)
KEYWORDS
frame, widget
Tk 8.4 frame(n)