Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/unix/volume26/mcast/part03

Text File | 1993-04-05 | 99.1 KB | 3,258 lines

Newsgroups: comp.sources.unix
From: [e-mail] (Casey Leedom)
Subject: v26i107: mcast - LLNL IP multicast implementation, V1.2.3, Part03/04
Sender: [e-mail]
Approved: [e-mail]

Submitted-By: [e-mail] (Casey Leedom)
Posting-Number: Volume 26, Issue 107
Archive-Name: mcast/part03

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 3 (of 4)."
# Contents:  ABSTRACT doc/cover.me include/netmcast/mcast.h
#   libmcast/_mc_read.c man/mc_getsockopt.2 man/mc_read.2
#   man/mc_recv.2 man/mc_send.2 man/mc_socket.2 man/mcast.4
#   man/mcast_newaddr.3 man/mcast_sopen.3 man/mcastd.8 test/mc_ping.c
# Wrapped by [e-mail] on Tue Apr  6 12:49:50 1993
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'ABSTRACT' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'ABSTRACT'\"
else
echo shar: Extracting \"'ABSTRACT'\" \(6014 characters\)
sed "s/^X//" >'ABSTRACT' <<'END_OF_FILE'
Identification:
X
X    Software Acronym: MCAST
X    Software Title: Multicast Testbed Server and Library System
X
X
Author Name(s) and Affiliations:
X
X    Leith Alan Leedom
X    LLNL/Computation
X
X
Software Completion Date:
X
X    May 15, 1992
X
X
Brief Description:
X
X    This software is an experimental implementation of a multicast
X    communication system.  It allows applications to communicate in a
X    broadcast-like manner with other applications.  The system consists
X    of a library interface modeled on the Berkeley socket abstraction, a
X    communications server, and a complete set of manual pages.
X
X
Method of Solution:
X
X    Multicast communication is simulated via the use of a communication
X    server.  Applications connect to the server via a provided library.
X
X    The server maintains several message groups which are created and
X    destroyed dynamically as applications connect to the server and
X    subscribe to message groups.  Only one message group can be
X    subscribed to on a connection at any one time.  Applications may
X    subscribe to multiple message groups simultaneously by establishing
X    multiple connections to the server.
X
X    When applications send messages to the server, the server resends
X    those messages to all other applications subscribed to the same
X    message group.
X
X
Computer(s) for which software is written:
X
X    IBM platforms supporting AIX 3.2 or later.
X    SGI platforms supporting IRIX 3.2 or later.
X    Sun platforms supporting SunOS 4.1.1 or later.
X
X
Operating System:
X
X    POSIX 1003.1-1990 with Berkeley socket, multiplexed I/O (select)
X    and uio (writev) extensions.
X
X
Programming Language(s) Used:
X
X    ANSI C X3.159-1989.
X
X
Software limitations:
X
X    All data is dynamically allocated with the C malloc(unsigned int)
X    library routine.  One fixed size array is used in the library to
X    maintain information on each application connection to the server.
X    This array is sized based on the Berkeley select constant FD_SETSIZE
X    from the C include file <sys/types.h>.
X
X
Unique Features of the Software:
X
X    The software is very simple and small.  It will allow researchers to
X    experiment easily with multicast communication in applications.  It
X    will allow researchers to experiment easily with different multicast
X    communication paradigms and application program interfaces via simple
X    code changes.
X
X
Related and Auxiliary Software:
X
X    This is the first release of this software.  It does not supersede any
X    other version.  It does not depend on any other software systems.
X    The ISIS system from Cornell University provides a similar, but much
X    more sophisticated and comprehensive capability.
X
X
Other Programming or Operating Information or Restrictions:
X
X    Files in the top level directory whose names consist of all capital
X    letters are general information files and should be read before all
X    others.
X
X    Files ending in ".c" and ".h" are ANSI C source files.  Files ending
X    in ".me" are troff documentation source files to be processed with
X    the "me" troff macro package.  Files ending in ".N," where N is a
X    single digit, are troff on-line manual pages to be processed with the
X    "man" troff macro package.  Files whose names start with "Makefile"
X    are part of the automatic software compilation and installation
X    system for the software.
X
X
Hardware Requirements:
X
X    No special hardware is required.
X
X
Time requirements:
X
X    Message transmission is usually bounded by less than 10 milliseconds
X    per 1024 bytes of message length on any reasonably performing system.
X
X
References:
X
X    Reference documents that are provided with this package:
X
X    ./ (general info)    description
X    -----------------    -----------
X    ABSTRACT ..............    this file
X    MEMO ..................    memo of understanding from software author
X                to LLNL software release office
X    README ................    overview of software and installation
X                instructions
X    TODO ..................    notes about remaining work to do on
X                software
X
X    ./man/ (manual pages)    description
X    ---------------------    -----------
X    mc_bind.2 .............    bind a name to a multicast socket
X    mc_close.2 ............    delete a multicast socket descriptor
X    mc_connect.2 ..........    create an association between a multicast
X                socket and a remote name
X    mc_fcntl.2 ............    multicast socket control
X    mc_getpeername.2 ......    get remote peer name of multicast socket
X    mc_getsockname.2 ......    get (local) name of multicast socket
X    mc_getsockopt.2 .......    get and set options on multicast sockets
X    mc_ioctl.2 ............    control multicast socket
X    mc_read.2 .............    read input from a multicast socket
X    mc_recv.2 .............    receive a message from a multicast socket
X    mc_send.2 .............    send a message to a multicast socket
X    mc_shutdown.2 .........    shut down part of a full-duplex connection
X    mc_socket.2 ...........    create a endpoint for multicast
X                communication
X    mc_write.2 ............    write output to a multicast socket
X    mcast.4 ...............    multicast protocol
X    mcast_getgroupbyname.3    get multicast address information
X    mcast_newaddr.3 .......    create a new, globally unique multicast
X                address
X    mcast_sopen.3 .........    open a connection to a multicast group
X    mcastd.8 ..............    multicast protocol server
X
X    ./doc/ (documentation)    description
X    ----------------------    -----------
X    cover.me ..............    cover page, contents, etc. for printer
X                documentation
X    notes.me ..............    general notes covering experiences with
X                the software
X
X    Reference documents not provided with this package:
X
X    Sechrest, S., "An Introductory 4.3BSD Interprocess Communication
X    Tutorial," 4.3BSD Document, UC Berkeley, 1986.
X
X    Leffler, S., Fabry, R., Joy, W., Lapsley, P., Miller, S.,
X    Torek, C., "An Advanced 4.3BSD Interprocess Communication
X    Tutorial," 4.3BSD Document, UC Berkeley, 1986.
X
X
Categorization and Keywords:
X
X    Subject Classification Code: P
X    Keywords: communications, computer networks, distributed data processing
END_OF_FILE
if test 6014 -ne `wc -c <'ABSTRACT'`; then
    echo shar: \"'ABSTRACT'\" unpacked with wrong size!
fi
# end of 'ABSTRACT'
fi
if test -f 'doc/cover.me' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'doc/cover.me'\"
else
echo shar: Extracting \"'doc/cover.me'\" \(7604 characters\)
sed "s/^X//" >'doc/cover.me' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.po 1.0in
X.ll 6.5in
X.nr pi 0n
X.de Hd
X.ds Vr \\$3
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/doc/RCS/cover.me,v 1.2 93/01/21 09:56:28 casey Exp $
X.of 'LLNL MCAST version \*(Vr''\*(Dt'
X.ef '\*(Dt''LLNL MCAST version \*(Vr'
X.(b C
X.sz +10
X.rs
X.sp 2.25in
LLNL MCAST
X.sp .5in
Distribution
X.sp 2in
Version \*(Vr
X\*(Dt
X.sz -10
X.)b
X.\" We delay defining the footer so it won't show up on the first page ...
X.of 'LLNL MCAST version \*(Vr''\*(Dt'
X.ef '\*(Dt''LLNL MCAST version \*(Vr'
X.pa
X.rs
X.sp 3.75in
Copyright (c) 1992 The Regents of the University of California.
All rights reserved.
X.pp
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
X.ip 1.
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
X.ip 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.
X.ip 3.
All advertising materials mentioning features or use of this software
must display the following acknowledgement:
X.(q
This product includes software developed by the University of
California, Berkeley and its contributors.
X.)q
X.ip 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.
X.pp
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
XFOR 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.
X.pa
X.(b C
X.sz +2
Contents
X.sz -2
X.)b
X.sp 3v
X.(x c
Introduction
X.)x 1
X.(x c
README
X.)x 2
X.(x c
ABSTRACT
X.)x 3
X.(x c
MEMO
X.)x 4
X.(x c
TODO
X.)x 5
X.(x c
Implementation notes
X.)x 6
X.(x c
Manual pages
X.)x 7
X.(x c
Include file sources
X.)x 8
X.(x c
Multicast server source
X.)x 9
X.(x c
Multicast application programming interface sources
X.)x 10
X.(x c
Multicast example application sources
X.)x 11
X.xp c
X.pa
X.(b C
X.sz +2
X1
X.sp 1v
Introduction
X.sz -2
X.)b
X.sp 3v
X.pp
This document contains the documentation and source code to the LLNL MCAST
software distribution version \*(Vr.
X.pp
The LLNL MCAST software is an experimental implementation of a
multicast communication system.  It allows applications to communicate
in a broadcast-like manner with other applications.  Multicast would
typically be used by the parts of a distributed application.
X.pp
The system consists of an application programming interface (API)
modeled on the Berkeley socket abstraction, a communications server,
and a complete set of manual pages.
X.pp
The communication server implements the multicast message passing
semantics.  A version of the system which uses network level multicast
facilities is planned, but we needed something up and running quickly
so other members of our project team could proceed with their work.
Hence, this version.  Our goal is to be able to slip in a true
multicast implementation using the same API under our applications
without the applications noticing the difference ...
X.pa
X.(b C
X.sz +2
X2
X.sp 1v
README
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X3
X.sp 1v
ABSTRACT
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X4
X.sp 1v
MEMO
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X5
X.sp 1v
TODO
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X6
X.sp 1v
Implementation notes
X.sz -2
X.)b
X.pa
X.(b C
X.sz +2
X7
X.sp 1v
Manual pages
X.sz -2
X.)b
X.sp 3v
X.pp
X.(x m
mc_bind.2
X.)x 1
X.(x m
mc_close.2
X.)x 2
X.(x m
mc_connect.2
X.)x 3
X.(x m
mc_fcntl.2
X.)x 4
X.(x m
mc_getpeername.2
X.)x 5
X.(x m
mc_getsockname.2
X.)x 6
X.(x m
mc_getsockopt.2
X.)x 7
X.(x m
mc_ioctl.2
X.)x 8
X.(x m
mc_read.2
X.)x 9
X.(x m
mc_recv.2
X.)x 10
X.(x m
mc_send.2
X.)x 11
X.(x m
mc_shutdown.2
X.)x 12
X.(x m
mc_socket.2
X.)x 13
X.(x m
mc_write.2
X.)x 14
X.(x m
mcast.4
X.)x 15
X.(x m
mcast_getgroupbyname.3
X.)x 16
X.(x m
mcast_newaddr.3
X.)x 17
X.(x m
mcast_sopen.3
X.)x 18
X.(x m
mcastd.8
X.)x 19
X.xp m
X.pa
X.(b C
X.sz +2
X8
X.sp 1v
Include file sources
X.sz -2
X.)b
X.sp 3v
X.pp
X.(x i
include/netmcast/mcast.h
X.)x 1
X.(x i
include/netmcast/mcastd.h
X.)x 2
X.xp i
X.pa
X.(b C
X.sz +2
X9
X.sp 1v
Multicast server source
X.sz -2
X.)b
X.sp 3v
X.(x d
mcastd/mcastd.c
X.)x 1
X.xp d
X.pa
X.(b C
X.sz +2
X10
X.sp 1v
Multicast application programming interface sources
X.sz -2
X.)b
X.sp 3v
X.pp
X.(x a
mc_lib.h
X.)x 1
X.(x a
X_mc_read.c
X.)x 2
X.(x a
X_mc_state.c
X.)x 3
X.(x a
X_mc_write.c
X.)x 4
X.(x a
mc_bind.c
X.)x 5
X.(x a
mc_close.c
X.)x 6
X.(x a
mc_connect.c
X.)x 7
X.(x a
mc_fcntl.c
X.)x 8
X.(x a
mc_getpeername.c
X.)x 9
X.(x a
mc_getsockname.c
X.)x 10
X.(x a
mc_getsockopt.c
X.)x 11
X.(x a
mc_ioctl.c
X.)x 12
X.(x a
mc_read.c
X.)x 13
X.(x a
mc_readv.c
X.)x 14
X.(x a
mc_recv.c
X.)x 15
X.(x a
mc_recvfrom.c
X.)x 16
X.(x a
mc_send.c
X.)x 17
X.(x a
mc_sendto.c
X.)x 18
X.(x a
mc_setsockopt.c
X.)x 19
X.(x a
mc_shutdown.c
X.)x 20
X.(x a
mc_socket.c
X.)x 21
X.(x a
mc_write.c
X.)x 22
X.(x a
mc_writev.c
X.)x 23
X.(x a
mcast_getgroupbyname.c
X.)x 24
X.(x a
mcast_newaddr.c
X.)x 25
X.(x a
mcast_sopen.c
X.)x 26
X.xp a
X.pa
X.(b C
X.sz +2
X11
X.sp 1v
Multicast example application sources
X.sz -2
X.)b
X.sp 3v
X.pp
X.(x t
mc_clock.c
X.)x 1
X.(x t
mc_hello.c
X.)x 2
X.(x t
mc_listen.c
X.)x 3
X.(x t
mc_ping.c
X.)x 4
X.(x t
mc_send.c
X.)x 5
X.xp t
END_OF_FILE
if test 7604 -ne `wc -c <'doc/cover.me'`; then
    echo shar: \"'doc/cover.me'\" unpacked with wrong size!
fi
# end of 'doc/cover.me'
fi
if test -f 'include/netmcast/mcast.h' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'include/netmcast/mcast.h'\"
else
echo shar: Extracting \"'include/netmcast/mcast.h'\" \(7755 characters\)
sed "s/^X//" >'include/netmcast/mcast.h' <<'END_OF_FILE'
X/*
X * $Header: /u0/casey/src/mcast/include/netmcast/RCS/mcast.h,v 1.5 93/03/17 11:35:50 casey Exp $
X */
X
X/*
X * Copyright (c) 1992 The Regents of the University of California.
X * All rights reserved.
X *
X * Redistribution and use in source and binary forms, with or without
X * modification, are permitted provided that the following conditions
X * are met:
X * 1. Redistributions of source code must retain the above copyright
X *    notice, this list of conditions and the following disclaimer.
X * 2. Redistributions in binary form must reproduce the above copyright
X *    notice, this list of conditions and the following disclaimer in the
X *    documentation and/or other materials provided with the distribution.
X * 3. All advertising materials mentioning features or use of this software
X *    must display the following acknowledgement:
X *    This product includes software developed by the University of
X *    California, Lawrence Livermore National Laboratory and its
X *    contributors.
X * 4. Neither the name of the University nor the names of its contributors
X *    may be used to endorse or promote products derived from this software
X *    without specific prior written permission.
X *
X * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X * SUCH DAMAGE.
X */
X
X#ifndef _MCAST_H_
X#define    _MCAST_H_
X
X/*
X * Multicast address format; used for both group and member addresses.
X * There's a lot missing here.  Multicast group addresses may really need
X * to be variable length and hierachical in order to be able to create
X * unique addresses in a totally distributed manner.  Who knows ...  There's
X * also the question of whether we should have separate address formats for
X * group and member addresses.  Since they both have the same design needs,
X * we've gone with a single address for now ...
X *
X * NOTE: The routine "mcast_newaddr" knows about the size and format of this
X * type.  If you change the type, mc_newaddr must also be changed
X * correspondingly.
X */
typedef struct mc_addr { /* MACHINE DEPENDENT */
X    unsigned int    host:32;    /* host ID (probably too small) */
X    unsigned int    process:32;    /* process ID */
X    unsigned int    time:32;    /* time (definitely too small) */
X    unsigned int    sequence:32;    /* sequence number (probably too small) */
X} mc_addr;
X
static const struct mc_addr MCADDR_ANY = {
X    0x00000000, 0x00000000, 0x00000000, 0x00000000
X};
static const struct mc_addr MCADDR_BROADCAST    = {
X    0xffffffff, 0xffffffff, 0xffffffff, 0xffffffff
X};
X/*
X * Note that, because of limitations in ANSI C's ability to use const
X * variables, ANSI C applications won't be able to use MCADDR_ANY and
X * MCADDR_BROADCAST to initialize static scope variables ...  Unfortunately
X * there is no other way to construct a constant instance of a structure
X * in C (or C++, but it's not quite so noticible there because C++ doesn't
X * suffer ANSI C's limitations with regard to static scope variable
X * initialization).
X */
X
X#define    MCADDR_EQ(a, b) \
X    (memcmp(&a, &b, sizeof(mc_addr)) == 0)
X
X
X/*
X * Multicast network layer message header format.  So far this is really
X * simple since the only transport implementation is via a server and much
X * of the ``protocol'' is handled implicitly by the server.  Questions abound
X * as to whether this should be layered on top of some other protcol like
X * IP and what will be required to support a real distributed implementation,
X * security to prevent random messages from disrupting communications, etc..
X * Note that it's impossible to send a multicast message without joining the
X * multicast group it's destined for.  Birman thinks this is wrong.
X */
typedef struct mc_header { /* MACHINE DEPENDENT */
X    unsigned int    version:8;    /* protocol version */
X    unsigned int    hlength:8;    /* header length */
X    unsigned int    :16;        /* pad to 32 bits */
X    unsigned int    length:32;    /* length of header + data */
X    mc_addr        group;        /* multicast group */
X    mc_addr        source;        /* source of this message */
X    mc_addr        destination;    /* destination of this message */
X    /* message data follows this minimum header */
X} mc_header;
X
X#define    MCVERSION    1        /* mcast protocol version number */
X#define    MCHEADER_CORE \
X    offsetof(mc_header, group)    /* includes version and lengths */
X#define    MCHEADER_MIN \
X    sizeof(mc_header)        /* minimum legal header length */
X#define    MCHEADER_MAX \
X    sizeof(mc_header)        /* maximum legal header length */
X
X/* multicast and atomic multicast protocols */
X#define    AF_MCAST    80        /* must be unique ... */
X#define    PF_MCAST    AF_MCAST    /* must be the same as AF_MCAST */
X#define    AF_AMCAST    81        /* must be unique ... */
X#define    PF_AMCAST    AF_AMCAST    /* must be the same as AF_AMCAST */
X
X
X/*
X * ``system calls'' (sic)
X */
X
typedef struct sockaddr_mcast {
X    short        family;        /* AF_MCAST or AF_AMCAST */
X    mc_addr        group;        /* multicast group ID */
X    mc_addr        member;        /* multicast group member ID */
X} sockaddr_mcast;
X
X#ifdef __cplusplus
extern "C" {
X#endif
int mc_bind(int s, const struct sockaddr *name, int namelen);
int mc_close(int s);
int mc_connect(int s, const struct sockaddr *name, int namelen);
int mc_fcntl(int s, int request, ...);
int mc_getpeername(int s, struct sockaddr *name, int *namelen);
int mc_getsockname(int s, struct sockaddr *name, int *namelen);
int mc_getsockopt(int s, int level, int optname, void *optval, int *optlen);
int mc_ioctl(int s, int request, ...);
int mc_read(int s, void *buf, size_t len);
int mc_readv(int s, const struct iovec *iov, int iovcnt);
int mc_recv(int s, void *buf, int len, int flags);
int mc_recvfrom(int s, void *buf, int len, int flags,
X        struct sockaddr *from, int *fromlen);
int mc_send(int s, const void *buf, int len, int flags);
int mc_sendto(int s, const void *buf, int len, int flags,
X          struct sockaddr *to, int tolen);
int mc_setsockopt(int s, int level, int optname,
X          const void *optval, int optlen);
int mc_shutdown(int s, int how);
int mc_socket(int domain, int type, int protocol);
int mc_write(int s, const void *buf, size_t len);
int mc_writev(int s, const struct iovec *iov, int iovcnt);
X#ifdef __cplusplus
X}
X#endif
X
X/* ioctl(2) defines.  "_IO*" macros are defined in <sys/ioctl.h> */
X#define    MCIOCLOOPBACK    _IOW('m', 127, int)
X                    /* set/clear loopback delivery */
X
X/* open(2) and fcntl(2) flag defines */
X#define    O_DEV1        0x0100        /* device specific flag 1 */
X#define    O_DEV2        0x0200        /* device specific flag 2 */
X#define    O_DEV3        0x0400        /* device specific flag 3 */
X#define    O_DEV4        0x0800        /* device specific flag 4 */
X#define    O_DEV        (O_DEV1|O_DEV2|O_DEV3|O_DEV4)
X
X#define    MCO_LOOPBACK    O_DEV1        /* loopback sender messages */
X
X/*
X * standard library
X */
X
typedef struct mcastent { /* really need a generic name/value system! */
X    char        *name;        /* official name of group */
X    char        **aliases;    /* alias list */
X    int        family;        /* address family */
X    mc_addr        address;    /* address bound to group */
X} mcastent;
X
X#ifdef __cplusplus
extern "C" {
X#endif
struct mcastent *mcast_getgroupbyname(const char *name, int domain);
int mcast_newaddr(struct mc_addr *addr);
int mcast_sopen(const char *group, int domain, int type, int mode);
X#ifdef __cplusplus
X}
X#endif
X
X#endif /* _MCAST_H_ */
END_OF_FILE
if test 7755 -ne `wc -c <'include/netmcast/mcast.h'`; then
    echo shar: \"'include/netmcast/mcast.h'\" unpacked with wrong size!
fi
# end of 'include/netmcast/mcast.h'
fi
if test -f 'libmcast/_mc_read.c' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'libmcast/_mc_read.c'\"
else
echo shar: Extracting \"'libmcast/_mc_read.c'\" \(6360 characters\)
sed "s/^X//" >'libmcast/_mc_read.c' <<'END_OF_FILE'
X/*
X * $Header: /u0/casey/src/mcast/libmcast/RCS/_mc_read.c,v 1.4 93/04/06 11:31:06 casey Exp $
X */
X
X/*
X * Copyright (c) 1992 The Regents of the University of California.
X * All rights reserved.
X *
X * Redistribution and use in source and binary forms, with or without
X * modification, are permitted provided that the following conditions
X * are met:
X * 1. Redistributions of source code must retain the above copyright
X *    notice, this list of conditions and the following disclaimer.
X * 2. Redistributions in binary form must reproduce the above copyright
X *    notice, this list of conditions and the following disclaimer in the
X *    documentation and/or other materials provided with the distribution.
X * 3. All advertising materials mentioning features or use of this software
X *    must display the following acknowledgement:
X *    This product includes software developed by the University of
X *    California, Lawrence Livermore National Laboratory and its
X *    contributors.
X * 4. Neither the name of the University nor the names of its contributors
X *    may be used to endorse or promote products derived from this software
X *    without specific prior written permission.
X *
X * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X * SUCH DAMAGE.
X */
X
X#ifndef lint
static char rcsid[] = "$Header: /u0/casey/src/mcast/libmcast/RCS/_mc_read.c,v 1.4 93/04/06 11:31:06 casey Exp $";
static char copyright[] =
X    "Copyright (c) 1992 The Regents of the University of California.\n"
X    "All rights reserved.\n";
static char classification[] =
X    "Unclassified\n";
X#endif
X
X
X/*
X * MCAST SYSLIB PRIVATE: _mc_read and _mc_pullup helper routines.
X */
X
X
X#include "mc_lib.h"
X
X
static int _read(int fd, void *buf, int len);
X
X
int
X_mc_read(int s, void *buf, size_t len, int flags, mc_addr *from)
X    /*
X     * Read len bytes into buf from multicast group attached to socket s.
X     * If from is non-NULL, assign source member address to *from.  Flags
X     * may be used to specify MSG_PEEK.
X     */
X{
X    mc_state *sp = &_mc_state[s];
X    int nread, cc;
X
X    if (flags & ~(MSG_PEEK|MSG_OOB)) {
X        errno = EINVAL;
X        return(-1);
X    }
X    if (flags & ~(MSG_PEEK)) {
X        /* we only support MSG_PEEK so far ... */
X        errno = ENOPROTOOPT;
X        return(-1);
X    }
X    if (sp->resid == 0)
X        if (_mc_pullup(s, sp->flags) < 0)
X            return(-1);
X    cc = min(len, sp->resid);
X    if (flags & MSG_PEEK)
X        cc = recv(s, buf, cc, MSG_PEEK);
X    else
X        cc = _read(s, buf, cc);
X    if (cc < 0)
X        return(-1);
X    if (!(flags & MSG_PEEK)) {
X        sp->resid -= cc;
X        if (sp->resid > 0 && sp->type != SOCK_STREAM) {
X            /* datagram type: throw away unread message bytes */
X            nread = _read(s, NULL, sp->resid);
X            if (nread < 0)
X                return(-1);
X            sp->resid = 0;
X        }
X    }
X    if (from != NULL)
X        *from = sp->source;
X    return(cc);
X}
X
X
int
X_mc_pullup(int s, int flags)
X    /*
X     * Pull up next message from server if there is no remaining data from
X     * last message.  Flags specifies whether pullup should block or not
X     * (O_NONBLOCK).  Returns amount of data available for reading.
X     */
X{
X    mc_state *sp = &_mc_state[s];
X    mc_header header;
X    int nread;
X    unsigned int ver, hlen, len;
X
X    again:
X    if (sp->resid != 0)
X        return(sp->resid);
X    if (flags & O_NONBLOCK) {
X        long n;
X        extern int ioctl(int, int, ...);
X
X        if (ioctl(s, FIONREAD, &n) < 0)
X            return(-1);
X        if (n == 0) {
X            errno = EAGAIN;
X            return(-1);
X        }
X    }
X    nread = _read(s, &header, sizeof(header));
X    if (nread < 0)
X        return(-1);
X    ver = header.version;
X    hlen = header.hlength;
X    len = ntohl(header.length);
X    if (ver != MCVERSION
X        || hlen < MCHEADER_MIN || hlen > MCHEADER_MAX
X        || len < hlen) {
X        (void)fprintf(stderr, "_mc_read: packet format error:"
X                  " ver = %d, hlen = %d, len = %d\n",
X                  (int)ver, (int)hlen, (int)len);
X        sp->state |= MC_CORRUPTED;
X        errno = EIO;
X        return(-1);
X    }
X    if (!MCADDR_EQ(header.group, sp->group)
X        || (!MCADDR_EQ(header.destination, MCADDR_BROADCAST)
X        && !MCADDR_EQ(header.destination, sp->local))
X        || ((sp->state & MC_CONNECTED)
X        && !MCADDR_EQ(header.destination, sp->remote))) {
X
X        /* misaddressed message; probably was just buffered up ... */
X        nread = _read(s, NULL, len-sizeof(header));
X        if (nread < 0)
X            return(-1);
X        else
X            goto again;
X    }
X    if (hlen > sizeof(header)) {
X        nread = _read(s, NULL, hlen-sizeof(header));
X        if (nread < 0)
X            return(nread);
X    }
X    sp->source = header.source;
X    sp->resid = len-hlen;
X    return(sp->resid);
X}
X
X
static int
X_read(int fd, void *buf, int len)
X    /*
X     * Read len bytes into buf from fd.  If buf is NULL, just read and
X     * throw away len bytes from fd ...
X     *
X     * While this may strike you as silly, it turns out that reads of large
X     * messages on STREAM sockets may return without having read all that
X     * you asked for.  Something in the underlaying transport is breaking
X     * the large messages up. (sigh) Read(2) should not prematurely return
X     * unless the file descriptor was set for non-blocking I/O!
X     *
X     * Another consideration is the possibility of the read call being
X     * interrupted by some underlaying asynchronous event system.  Thus, we
X     * need to check if a call returned with an EINTR and continue if so ...
X     */
X{
X    char *bp, trash[1024];
X    int nread, resid;
X
X    bp = buf;
X    resid = len;
X    while (resid > 0) {
X        if (buf == NULL)
X            nread = read(fd, trash, min(sizeof(trash), resid));
X        else
X            nread = read(fd, bp, resid);
X        if (nread < 0) {
X            if (errno == EINTR)
X                continue;
X            else
X                break;
X        }
X        if (nread == 0)
X            break;
X        bp += nread;
X        resid -= nread;
X    }
X    if (resid > 0) {
X        /* hopelessly out of sync with server */
X        _mc_state[fd].state |= MC_CORRUPTED;
X        errno = EIO;
X        return(-1);
X    }
X    return(len - resid);
X}
END_OF_FILE
if test 6360 -ne `wc -c <'libmcast/_mc_read.c'`; then
    echo shar: \"'libmcast/_mc_read.c'\" unpacked with wrong size!
fi
# end of 'libmcast/_mc_read.c'
fi
if test -f 'man/mc_getsockopt.2' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/mc_getsockopt.2'\"
else
echo shar: Extracting \"'man/mc_getsockopt.2'\" \(6401 characters\)
sed "s/^X//" >'man/mc_getsockopt.2' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/man/RCS/mc_getsockopt.2,v 1.1 92/10/16 18:23:02 casey Exp $
X.TH MC_GETSOCKOPT 2 \*(Dt
X.SH NAME
mc_getsockopt, mc_setsockopt \- get and set options on multicast sockets
X.SH SYNOPSIS
X.nf
X.ft B
X#include <sys/types.h>
X#include <sys/socket.h>
X#include <netmcast/mcast.h>
X
int
mc_getsockopt(int s, int level, int optname,
X              void *optval, int *optlen)
X
int
mc_setsockopt(int s, int level, int optname,
X              const void *optval, int optlen)
X.ft P
X.fi
X.SH DESCRIPTION
X.I Mc_getsockopt
and
X.I mc_setsockopt
manipulate the
X.I options
associated with a socket.  Options may exist at multiple
protocol levels; they are always present at the uppermost
X.I socket
level.
X.PP
When manipulating socket options the level at which the
option resides and the name of the option must be specified.
To manipulate options at the socket level,
X.I level
is specified as
SOL_SOCKET.
Currently multicast sockets don't support any other level.
X.PP
The parameters
X.I optval
and
X.I optlen
are used to access option values for
X.I setsockopt .
XFor
X.I getsockopt
they identify a buffer in which the value for the
requested option(s) are to be returned.  For
X.IR getsockopt ,
X.I optlen
is a value-result parameter, initially containing the
size of the buffer pointed to by
X.IR optval ,
and modified on return to indicate the actual size of
the value returned.  If no option value is
to be supplied or returned,
X.I optval
may be NULL.
X.PP
X.I Optname
and any specified options are passed uninterpreted to the appropriate
protocol module for interpretation.
The include file
X.I
X.I <sys/socket.h>
contains definitions for
socket level options, described below.
Options at other protocol levels vary in format and
name; consult the appropriate entries in
section
X4 of the manual.
X.PP
Most socket-level options utilize an
X.I int
parameter for
X.IR optval .
XFor
X.IR setsockopt ,
the parameter should be non-zero to enable a boolean option,
or zero if the option is to be disabled.
X.PP
The following options are recognized at the socket level for
multicast sockets.
XExcept as noted, each may be examined with
X.I getsockopt
and set with
X.I setsockopt .
X.PP
X.RS
X.nf
SO_SNDBUF    set buffer size for output
SO_RCVBUF    set buffer size for input
SO_TYPE    get the type of the socket (get only)
SO_ERROR    get and clear error on the socket (get only)
X.fi
X.RE
X.PP
SO_SNDBUF
and
SO_RCVBUF
are options to adjust the normal
buffer sizes allocated for output and input buffers, respectively.
The buffer size may be increased for high-volume connections,
or may be decreased to limit the possible backlog of incoming data.
The system places an absolute limit on these values.
X.PP
SO_TYPE
and
SO_ERROR
are options used only with
X.IR mc_getsockopt .
SO_TYPE
returns the type of the socket, such as
SOCK_STREAM;
it is useful for servers that inherit sockets on startup.
SO_ERROR
returns any pending error on the socket and clears
the error status.
It may be used to check for asynchronous errors on connected
datagram sockets or for other asynchronous errors.
X.SH COMPATIBILITY
The
X.I mc_getsockopt
and
X.I mc_setsockopt
calls emulate the
X.IR getsockopt (2)
and
X.IR setsockopt (2)
system calls for multicast socket descriptors created with the
X.IR mc_socket (2)
call.
See the manual pages for
X.IR getsockopt (2)
and
X.IR setsockopt (2)
for a description of the emulated semantics.
X.I Mc_getsockopt
and
X.I mc_setsockopt
do not provide any different semantics from
X.IR getsockopt (2)
and
X.IR setsockopt (2).
X.SH "RETURN VALUES"
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and the global integer variable
X.I errno
is set to indicate the error.
X.SH ERRORS
See the manual page for
X.IR getsockopt (2)
for a detailed list of errors associated with the general
X.IR getsockopt (2)
and
X.IR setsockopt (2)
system calls.
X.I Mc_getsockopt
and
X.I mc_setsockopt
themselves will fail if:
X.TP 20
X[EBADF]
X.I S
is not a valid multicast socket descriptor as returned by
X.IR mc_socket (2).
X.TP 20
X[EIO]
The socket state has become corrupted.  This is an artifact of a
client/server implementation of the multicast communication system.
X.TP 20
X[ENOPROTOOPT]
The option is unknown at the level indicated.
X.SH "SEE ALSO"
X.IR getsockopt (2),
X.IR mc_fcntl (2),
X.IR mc_ioctl (2),
X.IR mc_socket (2),
X.IR mcast (4)
X.SH STANDARDS
There are no current standards that address multicast communication.
The software described in this manual page is experimental and subject
to change at any time.
END_OF_FILE
if test 6401 -ne `wc -c <'man/mc_getsockopt.2'`; then
    echo shar: \"'man/mc_getsockopt.2'\" unpacked with wrong size!
fi
# end of 'man/mc_getsockopt.2'
fi
if test -f 'man/mc_read.2' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/mc_read.2'\"
else
echo shar: Extracting \"'man/mc_read.2'\" \(5043 characters\)
sed "s/^X//" >'man/mc_read.2' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/man/RCS/mc_read.2,v 1.3 93/01/16 20:01:48 casey Exp $
X.TH MC_READ 2 \*(Dt
X.SH NAME
mc_read, mc_readv \- read input from a multicast socket
X.SH SYNOPSIS
X.nf
X.ft B
X#include <unistd.h>
X#include <sys/types.h>
X#include <sys/uio.h>
X#include <sys/socket.h>
X#include <netmcast/mcast.h>
X
int
mc_read(int s, void *buf, size_t len)
X
int
mc_readv(int s, const struct iovec *iov, int iovcnt)
X.ft P
X.fi
X.SH DESCRIPTION
X.I Mc_read
attempts to read
X.I len
bytes of data from the object referenced by the multicast socket descriptor
X.I s
into the buffer pointed to by
X.IR buf .
X.I Mc_readv
performs the same action, but scatters the input data
into the
X.I iovcnt
buffers specified by the members of the
X.I iov
array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
The multicast socket
X.I s
must be bound before either
X.I mc_read
or
X.I mc_readv
can be used.
X.PP
XFor
X.IR mc_readv ,
the
X.I iovec
structure is defined as
X.PP
X.RS
X.nf
X.ta \w'struct'u +\w'caddr_tXXXX'u
struct iovec {
X    caddr_t    iov_base;
X    int    iov_len;
X};
X.DT
X.fi
X.RE
X.PP
XEach
X.I iovec
entry specifies the base address and length of an area
in memory where data should be placed.
X.I Mc_readv
will always fill an area completely before proceeding
to the next.
X.PP
Upon successful completion,
X.I mc_read
and
X.I mc_readv
return the number of bytes actually read and placed in the buffer.
The system guarantees to read the number of bytes requested if
the descriptor references a normal file that has that many bytes left
before the end-of-file, but in no other case.
X.SH COMPATIBILITY
The
X.I mc_read
and
X.I mc_readv
calls emulate the
X.IR read (2)
and
X.IR readv (2)
system calls for multicast socket descriptors created with the
X.IR mc_socket (2)
call.
See the manual pages for
X.IR read (2)
and
X.IR readv (2)
for a description of the emulated semantics.
X.I Mc_read
and
X.I mc_readv
do not provide any different semantics from
X.IR read (2)
and
X.IR readv (2).
X.SH "RETURN VALUES"
If successful, the
number of bytes actually read is returned. Upon reading end-of-file,
zero is returned.  (This happens when
X.IR mc_shutdown (2)
has been used to shutdown the receive half of the multicast socket.)
Otherwise, a -1 is returned and the global variable
X.I errno
is set to indicate the error.
X.SH ERRORS
See the manual pages for
X.IR read (2)
and
X.IR readv (2)
for a detailed list of errors associated with the general
X.IR read (2)
and
X.IR readv (2)
system calls.
X.I Mc_read
and
X.I mc_readv
themselves will fail if:
X.TP 20
X[EBADF]
X.I S
is not a valid multicast socket descriptor as returned by
X.IR mc_socket (2).
X.TP 20
X[EIO]
The socket state has become corrupted.  This is an artifact of a
client/server implementation of the multicast communication system.
X.TP 20
X[EPIPE]
No name has been bound to the multicast socket yet.
X.TP 20
X[EAGAIN]
The file was marked for non-blocking I/O,
and no data could be read immediately.
X.SH "SEE ALSO"
X.IR mc_socket (2),
X.IR mcast (4),
X.IR read (2),
X.IR select (2)
X.SH STANDARDS
There are no current standards that address multicast communication.
The software described in this manual page is experimental and subject
to change at any time.
END_OF_FILE
if test 5043 -ne `wc -c <'man/mc_read.2'`; then
    echo shar: \"'man/mc_read.2'\" unpacked with wrong size!
fi
# end of 'man/mc_read.2'
fi
if test -f 'man/mc_recv.2' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/mc_recv.2'\"
else
echo shar: Extracting \"'man/mc_recv.2'\" \(5752 characters\)
sed "s/^X//" >'man/mc_recv.2' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/man/RCS/mc_recv.2,v 1.1 92/10/16 18:23:04 casey Exp $
X.TH MC_RECV 2 \*(Dt
X.SH NAME
mc_recv, mc_recvfrom \- receive a message from a multicast socket
X.SH SYNOPSIS
X.nf
X.ft B
X#include <sys/types.h>
X#include <sys/socket.h>
X#include <netmcast/mcast.h>
X
int
mc_recv(int s, void *buf, int len, int flags)
X
int
mc_recvfrom(int s, void *buf, int len, int flags,
X            struct sockaddr *from, int *fromlen)
X.ft P
X.fi
X.SH DESCRIPTION
X.I Mc_recv
and
X.I mc_recvfrom
are used to receive messages from a multicast socket.
The multicast socket
X.I s
must be bound before either
X.I mc_recv
or
X.I mc_recvfrom
can be used.
X.PP
XFor
X.IR mc_recvfrom ,
if
X.I from
is non-NULL, the source address of the message is filled in.
X.I Fromlen
is a value-result parameter, initialized to the size of
the buffer associated with
X.IR from ,
and modified on return to indicate the actual size of the
address stored there.
The
X.I recv
is identical to
X.I recvfrom
with a NULL
X.I from
parameter.
As it is redundant, it may not be supported in future releases.
X.PP
X.I Buf
specifies where the received data should be stored in memory and
X.I len
specifies the amount of data requested.
The amount of data actually read into
X.I buf
is returned.
If a message is too long to fit in the supplied buffer,
excess bytes may be discarded depending on the type of socket
the message is received from (see
X.IR mc_socket (2).
X.PP
If no messages are available at the socket, the
receive call waits for a message to arrive, unless
the socket is non-blocking (see
X.IR mc_fcntl (2)
in which case the value
X-1 is returned and the external variable
X.I errno
set to
XEAGAIN.
The
X.IR select (2)
call may be used to determine when more data arrive.
X.PP
The
X.I flags
argument to a recv call is formed by \fIor\fPing
one or more of the values:
X.PP
X.RS
X.nf
MSG_PEEK    peek at incoming message
X.fi
X.RE
X.PP
The MSG_PEEK flag causes the receive operation to return data
from the beginning of the receive queue without removing that
data from the queue.
Thus, a subsequent receive call will return the same data.
X.SH COMPATIBILITY
The
X.I mc_recv
and
X.I mc_recvfrom
calls emulate the
X.IR recv (2)
and
X.IR recvfrom (2)
system calls for multicast socket descriptors created with the
X.IR mc_socket (2)
call.
See the manual pages for
X.IR recv (2)
and
X.IR recvfrom (2)
for a description of the emulated semantics.
X.I Mc_recv
and
X.I mc_recvfrom
do not provide any different semantics from
X.IR recv (2)
and
X.IR recvfrom (2).
X.SH "RETURN VALUES"
If successful, the
number of bytes actually received is returned.  Upon reading end-of-file,
zero is returned.  (This happens when
X.IR mc_shutdown (2)
has been used to shutdown the receive half of the multicast socket.)
Otherwise, a -1 is returned and the global variable
X.I errno
is set to indicate the error.
X.SH ERRORS
See the manual pages for
X.IR recv (2)
and
X.IR recvfrom (2)
for a detailed list of errors associated with the general
X.IR recv (2)
and
X.IR recvfrom (2)
system calls.
X.I Mc_recv
and
X.I mc_recvfrom
themselves will fail if:
X.TP 20
X[EBADF]
X.I S
is not a valid multicast socket descriptor as returned by
X.IR mc_socket (2).
X.TP 20
X[EIO]
The socket state has become corrupted.  This is an artifact of a
client/server implementation of the multicast communication system.
X.TP 20
X[EPIPE]
No name has been bound to the multicast socket yet.
X.TP 20
X[EINVAL]
X.I Fromlen
is less than
X.IR sizeof ( "struct sockaddr_mcast" ).
X.TP 20
X[EAGAIN]
The file was marked for non-blocking I/O,
and no data could be read immediately.
X.SH "SEE ALSO"
X.IR mc_fcntl (2),
X.IR mc_read (2),
X.IR mc_getsockopt (2),
X.IR mc_socket (2),
X.IR mcast (4),
X.IR recv (2),
X.IR select (2)
X.SH STANDARDS
There are no current standards that address multicast communication.
The software described in this manual page is experimental and subject
to change at any time.
END_OF_FILE
if test 5752 -ne `wc -c <'man/mc_recv.2'`; then
    echo shar: \"'man/mc_recv.2'\" unpacked with wrong size!
fi
# end of 'man/mc_recv.2'
fi
if test -f 'man/mc_send.2' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/mc_send.2'\"
else
echo shar: Extracting \"'man/mc_send.2'\" \(5986 characters\)
sed "s/^X//" >'man/mc_send.2' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/man/RCS/mc_send.2,v 1.2 93/01/16 20:02:26 casey Exp $
X.TH MC_SEND 2 \*(Dt
X.SH NAME
mc_send, mc_sendto \- send a message to a multicast socket
X.SH SYNOPSIS
X.nf
X.ft B
X#include <sys/types.h>
X#include <sys/socket.h>
X#include <netmcast/mcast.h>
X
int
mc_send(int s, const void *buf, int len, int flags)
X
int
mc_sendto(int s, const void *buf, int len, int flags,
X          const struct sockaddr *to, int tolen)
X.ft P
X.fi
X.SH DESCRIPTION
X.I Mc_send
and
X.I mc_sendto
are used to transmit messages on a multicast socket.
The multicast socket
X.I s
must be bound before either
X.I mc_send
can be used.
X.PP
If
X.I mc_sendto
is used on an unbound multicast socket,
X.I mc_sendto
will automatically bind a name to the socket using the multicast group
specified in
X.I to
a new, unique local group member address (see
X.IR mcast_newaddr (3)).
The remote member association will be set to MCADDR_BROADCAST.  To change
the remote member association see
X.IR mc_connect (2).
X.PP
XFor
X.IR mc_sendto ,
if
X.I to
is non-NULL, it contains the remote group member address that the message
it to be sent to.
X.I Tolen
specifies the length of
X.IR to .
The
X.I send
is identical to
X.I sendto
with a NULL
X.I to
parameter.
As it is redundant, it may not be supported in future releases.
X.PP
X.I Buf
specifies where the data to be sent is located in memory and
X.I len
specifies the amount of data to be sent.
If the message is too long to pass atomically through the
underlying protocol, the error
XEMSGSIZE
is returned, and
the message is not transmitted.
X.PP
If no messages space is available at the socket to hold
the message to be transmitted, then
X.I mc_send
normally blocks, unless the socket has been placed in
non-blocking I/O mode (see
X.IR mc_fcntl (2))
in which case the value
X-1 is returned and the external variable
X.I errno
set to
XEAGAIN.
The
X.IR select (2)
call may be used to determine when it is possible to
send more data.
X.PP
The
X.I flags
parameter may include one or more of the following:
X.PP
X.RS
X.nf
no flags currently supported
X.fi
X.RE
X.PP
X.SH COMPATIBILITY
The
X.I mc_send
and
X.I mc_sendto
calls emulate the
X.IR send (2)
and
X.IR sendto (2)
system calls for multicast socket descriptors created with the
X.IR mc_socket (2)
call.
See the manual pages for
X.IR send (2)
and
X.IR sendto (2)
for a description of the emulated semantics.
X.I Mc_send
and
X.I mc_sendto
do not provide any different semantics from
X.IR send (2)
and
X.IR sendto (2).
X.SH "RETURN VALUES"
If successful, the number of bytes actually written is returned.
Otherwise, a -1 is returned and the global variable
X.I errno
is set to indicate the error.
X.SH ERRORS
See the manual pages for
X.IR send (2)
and
X.IR sendto (2)
for a detailed list of errors associated with the general
X.IR send (2)
and
X.IR sendto (2)
system calls.
X.I Mc_send
and
X.I mc_sendto
themselves will fail if:
X.TP 20
X[EBADF]
X.I S
is not a valid multicast socket descriptor as returned by
X.IR mc_socket (2).
X.TP 20
X[EIO]
The socket state has become corrupted.  This is an artifact of a
client/server implementation of the multicast communication system.
X.TP 20
X[EPIPE]
No name has been bound to the multicast socket yet.
X.TP 20
X[EPIPE]
X.I Mc_shutdown
was used to shutdown sending on the multicast socket.  All further attempts
to write on the multicast socket will return EPIPE.
X.TP 20
X[EINVAL]
X.I Tolen
is less than
X.IR sizeof ( "struct sockaddr_mcast" ).
X.TP 20
X[EINVAL]
X.I To
specified a remote group member address of MCADDR_ANY.
X.TP 20
X[EAFNOSUPPORT]
X.I To
specified an address family other than AF_MCAST.
X.TP 20
X[EISCONN]
X.I S
has been bound and
X.I to
specified a multicast group different from that already bound to
X.IR s .
X.TP 20
X[EAGAIN]
The file was marked for non-blocking I/O,
and no data could be sent immediately.
X.SH "SEE ALSO"
X.IR mc_fcntl (2),
X.IR mc_getsockopt (2),
X.IR mc_socket (2),
X.IR mc_write (2),
X.IR mcast (4),
X.IR send (2),
X.IR select (2)
X.SH STANDARDS
There are no current standards that address multicast communication.
The software described in this manual page is experimental and subject
to change at any time.
END_OF_FILE
if test 5986 -ne `wc -c <'man/mc_send.2'`; then
    echo shar: \"'man/mc_send.2'\" unpacked with wrong size!
fi
# end of 'man/mc_send.2'
fi
if test -f 'man/mc_socket.2' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/mc_socket.2'\"
else
echo shar: Extracting \"'man/mc_socket.2'\" \(5520 characters\)
sed "s/^X//" >'man/mc_socket.2' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/man/RCS/mc_socket.2,v 1.3 93/01/16 20:03:14 casey Exp $
X.TH MC_SOCKET 2 \*(Dt
X.SH NAME
mc_socket \- create a endpoint for multicast communication
X.SH SYNOPSIS
X.nf
X.ft B
X#include <sys/types.h>
X#include <sys/socket.h>
X#include <netmcast/mcast.h>
X
int
mc_socket(int domain, int type, int protocol)
X.ft P
X.fi
X.SH DESCRIPTION
X.I Mc_socket
creates an endpoint for multicast communication and returns a descriptor.
The
X.I domain
parameter specifies a communications domain within which
communication will take place; this selects the protocol family
which should be used.
These families are defined in the include file
X.IR <netmcast/mcast.h> .
The currently understood formats are
X.PP
X.ta \w'SOCK_SEQPACKETXXX'u
X.RS
X.nf
PF_MCAST    multicast protocols
PF_AMCAST    atomic (globally ordered) multicast protocols
X.fi
X.RE
X.PP
The socket has the indicated
X.IR type ,
which specifies the semantics of communication.  Currently
defined types are:
X.PP
X.RS
X.nf
SOCK_DGRAM    unsequenced, unreliable packet stream
SOCK_RDM    unsequenced, reliable packet stream
SOCK_SEQPACKET    sequenced, reliable packet stream
SOCK_STREAM    sequenced, reliable byte stream
X.fi
X.RE
X.DT
X.PP
XFor PF_AMCAST, only SOCK_SEQPACKET and SOCK_STREAM are supported.  See
X.IR mcast (4)
for a description of these families and types.
X.PP
The
X.Fa protocol
specifies a particular protocol to be used with the socket.
Normally only a single protocol exists to support a particular
socket type within a given protocol family.  However, it is possible
that many protocols may exist, in which case a particular protocol
must be specified in this manner.  The protocol number to use is
particular to the \*(lqcommunication domain\*(rq in which communication
is to take place; see
X.IR protocols (5).
XFor
X.I mc_socket
only protocol
X.B 0
is supported for any of the types.
X.SH COMPATIBILITY
The
X.I mc_socket
call emulates the
X.IR socket (2)
system call for multicast socket descriptors created with the
X.IR mc_socket (2)
call.
See the manual page for
X.IR socket (2)
for a description of the emulated semantics.
X.I Mc_socket
does not provide any different semantics from
X.IR socket (2).
X.SH "RETURN VALUES"
A -1 is returned if an error occurs, otherwise the return
value is a descriptor referencing the multicast socket.
X.SH ERRORS
See the manual page for
X.IR socket (2)
for a detailed list of errors associated with the general
X.IR socket (2)
system call.
X.I Mc_socket
itself will fail if:
X.TP 20
X[EPFNOSUPPORT]
The
X.I domain
specified is not
PF_MCAST.
X.TP 20
X[EPROTONOSUPPORT]
X.I Type
is not one of SOCK_DGRAM, SOCK_RDM, SOCK_SEQPACKET, or SOCK_STREAM.
X.TP 20
X[EPROTONOSUPPORT]
The
X.I protocol
is not
X.BR 0 .
X.TP 20
X[EMFILE]
The fixed size multicast socket state space was exceeded.  So shoot me
for putting in a fixed limit.  This is just an experimental package to
demonstrate proof of concept ...
X.TP 20
X[EHOSTUNREACH]
The address couldn't be determined of the machine running the
multicast communication server.  This is an artifact of a
client/server implementation of the multicast communication system.
X.SH SEE ALSO
X.IR mcast (4),
X.IR mcast_getgroupbyname (3),
X.IR mcast_newaddr (3),
X.IR mcast_sopen (3),
X.IR mc_bind (2),
X.IR mc_close (2),
X.IR mc_connect (2),
X.IR mc_fcntl (2),
X.IR mc_getsockname (2),
X.IR mc_getsockopt (2),
X.IR mc_ioctl (2),
X.IR mc_read (2),
X.IR mc_recv (2),
X.IR mc_send (2),
X.IR mc_shutdown (2),
X.IR mc_write (2),
X.IR select (2),
X.IR socket (2)
X.SH STANDARDS
There are no current standards that address multicast communication.
The software described in this manual page is experimental and subject
to change at any time.
END_OF_FILE
if test 5520 -ne `wc -c <'man/mc_socket.2'`; then
    echo shar: \"'man/mc_socket.2'\" unpacked with wrong size!
fi
# end of 'man/mc_socket.2'
fi
if test -f 'man/mcast.4' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/mcast.4'\"
else
echo shar: Extracting \"'man/mcast.4'\" \(13604 characters\)
sed "s/^X//" >'man/mcast.4' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/man/RCS/mcast.4,v 1.3 93/01/16 20:06:23 casey Exp $
X.TH MCAST 4 \*(Dt
X.SH NAME
mcast \- multicast protocol
X.SH SYNOPSIS
X.nf
X.ft B
X#include <sys/types.h>
X#include <sys/socket.h>
X#include <netmcast/mcast.h>
X
int
mc_socket(int domain, int type, int protocol)
X.ft P
X.fi
X.SH DESCRIPTION
The multicast protocol families allow applications to communicate in a
broadcast-like manner with other applications.  Multicast would typically
be used by the parts of a distributed application.  The communication
style may be message or stream oriented; reliable or unreliable;
unsequenced, single source sequenced or globally sequenced (although not all
combinations are allowed; see below).
X.PP
Within each multicast communication domain, there are a large number of
potential multicast
X.IR groups .
When a message is sent to a multicast group, it will normally be received
by all applications which are subscribed to the group for reading.  An
important exception to this is the
X.IR "multicast unicast"
which is only sent to a particular multicast group
X.IR member .
Multicast unicasts can be performed either individually via
X.I mc_sendto
or set up as the normal state of affairs with
X.IR mc_connect .
X.PP
A multicast group can be thought of as a
X.I "virtual network"
which is some subset of connected physical networks.  Every multicast
group member is a process which executes on a node of the
virtual/physical network.  Each multicast group has an address unique
from all others within its communication domain and every member of a
multicast group has an address unique from all other members of that
multicast group.
X.PP
Multicast groups can be created on demand and discarded just as
easily.  One paradigm of operation is to treat multicast groups in much
the same way as UNIX shells treat pipes: i.e. a process creates
one or more multicast groups, forks one or more children, and passes the
multicast groups to the children for use in communicating among themselves.
X.I Well known
multicast groups are also possible.
X.PP
Connections to multicast groups are formed by calling
X.I mc_socket
to create a socket in one of the multicast protocol family domains and
then binding a multicast group name to the socket via
X.I mc_bind
X(though there are other ways to bind names).  Further details of the
multicast socket's operation can be specified with
X.I mc_setsockopt
and
X.IR mc_fcntl .
Once such a connection is formed, messages may be read and written via
X.I mc_read
and
X.I mc_write
X(and a few other variations).
While a multicast connection is alive,
X.IR select (2)
can be used to poll or block for input data or output buffer space
availability just as with other file descriptor types.  Finally a
connection can be dissolved via
X.IR mc_close .
X.PP
As mentioned above, once a multicast socket has been created with
X.IR mc_socket ,
a name must be bound to it before it can be used.  For multicast sockets,
this name consists of a multicast address family, group address and group
member address.
X.PP
X.RS
X.nf
X.ta \w'struct'u +\w'struct mc_addr;XXXX'u +\w'memberXXXX'u
struct sockaddr_mcast {
X    short    family;    /* AF_MCAST or AF_AMCAST */
X    struct mc_addr    group;    /* multicast group ID */
X    struct mc_addr    member;    /* multicast group member ID */
X};
X.DT
X.fi
X.RE
X.PP
The process of binding a name to a multicast socket corresponds
to joining a multicast group and choosing a unique multicast group member
identifier.
X.I Mc_bind
is used to bind names to multicast sockets.  If a socket hasn't had a
name bound to it, then an
X.I mc_connect (2)
or an
X.I mc_sendto (2)
will cause an implicit bind to take place.
Once a name has been bound to a multicast socket it may not be changed.
X.PP
Implicit in the above is the fact that a multicast socket can only be
connected to
X.I one
multicast group.  If an application wants to join more than one multicast
group, it must acquire a separate multicast socket for each group.
Multiplexing I/O activity between multiple multicast sockets and other
file descriptors can be managed with the
X.IR select (2)
call.
X.PP
Unlike other communication domains, reliable type sockets in the
multicast domain are not required to be in a
X.I connected
state before being used.  This is because there is no parallel to the
asymmetric client/server model of other domains.  When we speak of a
socket being
X.I connected
to a multicast group we mean that it is bound to a multicast group.  For
unreliable sockets, this merely means giving a name to the socket which
will be used for the source address of all out-going messages and to set
up a multicast listening filter.  For reliable sockets, naming a socket
also causes reliable communication transports to be set up with all hosts
on all directly connected networks which have processes connected to the
multicast group.
X.PP
The supported multicast protocol families are as follows:
X.ta \w'SOCK_SEQPACKETXXX'u
X.RS
X.nf
PF_MCAST    multicast protocols
PF_AMCAST    atomic (globally ordered) multicast protocols
X.fi
X.RE
The supported socket types in the multicast domains are as follows:
X.PP
X.RS
X.nf
SOCK_DGRAM    unsequenced, unreliable packet stream
SOCK_RDM    unsequenced, reliable packet stream
SOCK_SEQPACKET    sequenced, reliable packet stream
SOCK_STREAM    sequenced, reliable byte stream
X.fi
X.RE
X.DT
X.PP
XFor PF_AMCAST, only SOCK_SEQPACKET and SOCK_STREAM are supported.
X.PP
SOCK_DGRAM offers an unreliable, unsequenced, possibly duplicated
message-oriented communication channel to an application.  Only a best
effort will be made to get the message to the destination
application(s).
X.PP
In the multicast domains, the only difference between SOCK_RDM,
SOCK_SEQPACKET and SOCK_STREAM is in the presentation semantics offered
to an application.  They all reliably deliver data between multicast
peers without loss or duplication.  The receiving communication software
provides the reliably delivered data to the application as an unsequenced
message stream, a sequenced message stream or a byte stream.
X.PP
In the PF_MCAST domain, the sequencing offered by SOCK_SEQPACKET and
SOCK_STREAM is only with respect to the sender.  Different receivers may
see different message interleavings from multiple senders.
X.PP
In the PF_AMCAST protocol family, all messages on a multicast group will
be received in exactly the same order by all receivers.  That is, if one
member of multicast group
X.I G
receives message
X.I A
before message
X.IR B ,
X.I all
members of multicast group
X.I G
will receive message
X.I A
before message
X.IR B .
This is radically different from PF_MCAST in this respect and comes at a
price since message sequencing must be globally coordinated between all
members of a multicast group.  This semantic is useful for distributed
locking schemes and other similar distributed algorithms.
X.PP
XFor multicast sockets, each write operation defines a single logical
message and reads will not read across message boundaries.
XFor sockets with message presentation semantics
X(SOCK_SEQPACKET, SOCK_RDM, and SOCK_DGRAM),
if only part of a message is read, the
remainder is discarded.
XFor SOCK_STREAM sockets, if only part of a message is read, the remainder
is left available for future read operations.
X.SH EXAMPLES
In the following examples, all error detection and recovery have been
omitted in the interest of brevity and clarity.  Real applications would
test the results of all system calls.
X.PP
What example set would be complete without \*(lqhello world?\*(rq
The following example opens a connection to the
X.B hello-world-group
and sends the message
X.B "hello world!"
onto it.
X.PP
X.RS
X.nf
int s;
X
s = mcast_sopen("hello-world-group", PF_MCAST, SOCK_STREAM, O_WRONLY);
X(void)mc_write(s, "hello world!\\n", 13);
X(void)mc_close(s);
X.fi
X.RE
X.PP
You can think of the next example as one half of the popular
X.IR cat (1)
program.  It opens a connection to a multicast group, reads messages
from that group and outputs them onto standard output, and terminates when
it reads a zero length message.
X.PP
X.RS
X.nf
int s;
char *group = "...";
X
s = mcast_sopen(group, PF_MCAST, SOCK_STREAM, O_RDONLY);
for (;;) {
X    char buf[1024];
X    int nread, nwrite;
X
X    nread = mc_read(s, buf, sizeof(buf));
X    if (nread == 0)
X        break;
X    (void)write(STDOUT_FILENO, buf, nread);
X}
X(void)mc_close(s);
X.fi
X.RE
X.SH COMPATIBILITY
This is experimental software.  It is not compatible with any other
network protocols.  Not even other multicast protocols.  The fact that
we were able to fit the interface into the Berkeley networking socket
paradigm is a tribute to equal parts of stubbornness and the surprising
flexibility of that paradigm.  However, this software, including its
interface specification may change at any time.
X.PP
Since the software is
X.I not
part of the stock system software, some effort will probably be necessary
to use it.  Typically this will entail compiling your source with flags
something like
X.RI -I/ usr / local / include
and linking your program with flags
X.RI -L/ usr / local / lib
and
X.RI -l mcast .
Installations will differ from machine to machine and some installations
may not require anything special to access the multicast software.
X.PP
The current version of the multicast transport is implemented via a server,
X.IR mcastd (8),
which simulates multicast communication for its clients.  This fact
shouldn't affect most applications since it's completely hidden by the
application programming interface (API) presented in this and other
manual pages.  The hope is to replace this transport implementation with
a true network based multicast implementation in the future.  In the mean
time, this implementation allows people to work with the abstraction and
change it to experiment with it and its interface.  See
X.IR mcastd (8)
for more details about this implementation.
X.PP
One area where the current server implementation will affect applications
is in how the API software determines how to get to the server:
X.TP 5
To locate the server host:
If the environment variable MCASTD_SERVER is defined, it will be used as the
name of the host
X.I mcastd
is running on.  Otherwise, the host name
X.IR mcastd - server
will be used.  If the chosen host name is not found by
X.IR gethostbyname (3),
the address for the local host (via its loopback address) will be used.
X.TP 5
To determine the service port:
If the environment variable MCASTD_PORT is defined, it will be used as the
port number to use to contact
X.IR mcastd .
Otherwise, the service
X.IR mcast / tcp
will be looked up via
X.IR getservbyname (3).
XFinally, if that doesn't work, an installation configuration defined
constant will be used.  In the software distribution this is defined to be
X.IR 8001 .
X.SH PORTABILITY
Where possible, this software has been written to conform to ANSI C as
defined in
X.I "ANSI X3.159-1989"
and
POSIX 1003.1 as defined in
X.IR "IEEE Std 1003.1-1990" .
Unfortunately there are no standards available yet for networking APIs.
Where we were forced to step beyond the ANSI C and POSIX 1003.1 standards,
we chose to use the BSD
X.RI ( "Berkeley Software Distribution" )
definitions.  As such, it depends on the BSD
X.I socket
facilities, I/O control mechanisms, etc.
X.SH "SEE ALSO"
X.IR mc_bind (2),
X.IR mc_close (2),
X.IR mc_connect (2),
X.IR mc_fcntl (2),
X.IR mc_getpeername (2),
X.IR mc_getsockname (2),
X.IR mc_getsockopt (2),
X.IR mc_ioctl (2),
X.IR mc_read (2),
X.IR mc_recv (2),
X.IR mc_send (2),
X.IR mc_shutdown (2),
X.IR mc_socket (2),
X.IR mc_write (2),
X.IR mcast_getgroupbyname (3),
X.IR mcast_newaddr (3),
X.IR mcast_sopen (3),
X.IR mcastd (8m),
X.IR socket (2)
X.SH STANDARDS
There are no current standards that address multicast communication.
The software described in this manual page is experimental and subject
to change at any time.
END_OF_FILE
if test 13604 -ne `wc -c <'man/mcast.4'`; then
    echo shar: \"'man/mcast.4'\" unpacked with wrong size!
fi
# end of 'man/mcast.4'
fi
if test -f 'man/mcast_newaddr.3' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/mcast_newaddr.3'\"
else
echo shar: Extracting \"'man/mcast_newaddr.3'\" \(5275 characters\)
sed "s/^X//" >'man/mcast_newaddr.3' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/man/RCS/mcast_newaddr.3,v 1.1 92/10/16 18:23:08 casey Exp $
X.TH MCAST_NEWADDR 3 \*(Dt
X.SH NAME
mcast_newaddr \- create a new, globally unique multicast address
X.SH SYNOPSIS
X.nf
X.ft B
X#include <sys/types.h>
X#include <sys/socket.h>
X#include <netmcast/mcast.h>
X
int
mcast_newaddr(struct mc_addr *addr)
X.ft P
X.fi
X.SH DESCRIPTION
X.I Mcast_newaddr
creates a new multicast address and leaves it in
X.IR addr .
The address is guaranteed to be unique across all processes on all
hosts on all nets.  These addresses may be used for both new multicast
group identifiers and multicast group member addresses.  Further, once
a multicast address is created, it is completely opaque and is not
associated with the creating process, host, or network in any way.
Thus, a process is free to migrate to another host and continue to use
the same address.
X.PP
The address is created in a totally distributed manner; new name
generation does not depend on any complex, time consuming negotiation
with other hosts.  Thus, the speed of name generation is generally
limited only by the speed of the host.  (Well, almost, see below.)
X.PP
The current address generation algorithm incorporates host/process
identification, host clock, and an intra-clock-tick sequence number
to implement the distributed uniqueness property.  Note again that
once an address has been created, it is completely opaque.
X.PP
Addresses which are created close in time to each other may not be
distinguished via the creating host's clock.  For that reason, an
intra-clock-tick sequence number is used to further distinguish
addresses.  Since that sequence number is finite in the current
implementation, there is a finite rate at which address can be
generated.  That limit is currently approximately four billion per
second.  We refuse to humiliate ourselves by making some prediction as
to how long that rate should be sufficient.  The rate of progress in
the industry usually makes all such predictions ludicrous within a few
weeks of their utterance ...
X.SH COMPATIBILITY
X.I Mcast_newaddr
is unique to the experimental multicast implementation.  Given the
need for generating distributed, unique identifiers in the distributed
computing community, it shouldn't even be associated with multicast.
However, since we wanted to get on with our work and since the
identifiers directly corresponded to our multicast addresses, we
decided not to lose time working on a more general scheme.  In any
case, it would be easy enough to do that at a later time and replace
the definitions of
X.I mc_addr
and
X.I mcast_newaddr
with references to a general distributed identifier and identifier
creation routine.
X.SH "RETURN VALUES"
Upon successful completion, a value of 0 is returned and a new address is
left in
X.IR addr .
Otherwise, a value of -1 is returned and the global integer variable
X.I errno
is set to indicate the error.
X.SH ERRORS
X.TP 20
X[EAGAIN]
Unable to create a new multicast address at the current time.  An attempt
at a later time may be successful.
X.TP 20
X[EFAULT]
X.I Addr
is not in the user's memory map or is misaligned.
X.SH "SEE ALSO"
X.IR mcast (4),
X.IR mcast_getgroupbyname (3),
X.IR mc_socket (2)
X.SH STANDARDS
There are no current standards that address multicast communication.
The software described in this manual page is experimental and subject
to change at any time.
END_OF_FILE
if test 5275 -ne `wc -c <'man/mcast_newaddr.3'`; then
    echo shar: \"'man/mcast_newaddr.3'\" unpacked with wrong size!
fi
# end of 'man/mcast_newaddr.3'
fi
if test -f 'man/mcast_sopen.3' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/mcast_sopen.3'\"
else
echo shar: Extracting \"'man/mcast_sopen.3'\" \(5587 characters\)
sed "s/^X//" >'man/mcast_sopen.3' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/man/RCS/mcast_sopen.3,v 1.3 93/01/16 20:08:24 casey Exp $
X.TH MCAST_SOPEN 3 \*(Dt
X.SH NAME
mcast_sopen \- open a connection to a multicast group
X.SH SYNOPSIS
X.nf
X.ft B
X#include <fcntl.h>
X#include <sys/types.h>
X#include <sys/socket.h>
X#include <netmcast/mcast.h>
X
int
mcast_sopen(const char *group, int domain, int type, int mode)
X.ft P
X.fi
X.SH DESCRIPTION
X.I Mcast_sopen
creates a multicast socket in the
X.I domain
multicast protocol family of
X.IR type ,
sets various features based on
X.IR mode ,
and connects the socket to the multicast group specified by
X.IR group .
The initialized socket is returned.
This is basically a helper routine to hide a lot of the ugliness
associated with getting a multicast socket set up for use.
X.I Mcast_sopen
is meant to generally emulate the spirit of the
X.IR open (2)
call but for multicast groups instead of files.
X.PP
X.I Domain
is one of PF_MCAST or PF_AMCAST.
X.I Type
is one of SOCK_DGRAM, SOCK_RDM, SOCK_SEQPACKET, or SOCK_STREAM.
XFor PF_AMCAST, only SOCK_SEQPACKET and SOCK_STREAM are supported.
See
X.IR mc_socket (2)
for information regarding multicast socket creation and types.  See
X.IR mcast (4)
for information on multicast protocol operation and presentation
semantics.
X.PP
X.I Mode
should contain one of O_RDWR, O_RDONLY, or O_WRONLY
X.IR or 'ed
with any legal
X.IR mc_fcntl (2)
XF_SETFL flag set.  If O_RDONLY is specified, an
X.I mc_shutdown
with
X.IR how =1
will be performed on the socket.  Similarly, if O_WRONLY is specified, an
X.I mc_shutdown
with
X.IR how =2
will be performed on the socket.
The remaining mode bits will be passed to
X.IR mc_fcntl (2).
X.PP
Note that this gives a completely different semantic for O_NONBLOCK from
X.IR open (2).
XFor
X.IR open ,
O_NONBLOCK specifies that the
X.I open
shouldn't block if the file being opened corresponds to a device \(em
such as a tty \(em that can block during an open operation.  Further,
using O_NONBLOCK in an
X.I open
call does
X.I not
cause the returned file descriptor to be put in non-blocking I/O
mode (as via usage of O_NONBLOCK with
X.IR fcntl ).
X.PP
XFor
X.I mcast_sopen
on the other hand, using O_NONBLOCK
X.I does
cause the file descriptor to be put into non-blocking I/O mode since
the non-access control mode bits are passed to
X.IR mc_fcntl .
X.SH COMPATIBILITY
X.I Mcast_sopen
is unique to the experimental multicast implementation.  It's actually
amazingly convenient.  Someone should do something similar for the
other network protocol families.  Eg:
X.IR inet_sopen (...).
X.SH "RETURN VALUES"
A -1 is returned if an error occurs, otherwise the return
value is a descriptor referencing the multicast socket connected
to the specified group.
X.SH ERRORS
X.TP 20
X[EPROTONOSUPPORT]
X.I Type
is not one of SOCK_DGRAM, SOCK_RDM, SOCK_SEQPACKET, or SOCK_STREAM.
X.TP 20
X[EINVAL]
X.I Mode
contained an illegal value.
X.TP 20
X[EMFILE]
The fixed size multicast socket state space was exceeded.  So shoot me
for putting in a fixed limit.  This is just an experimental package to
demonstrate proof of concept ...
X.TP 20
X[EHOSTUNREACH]
The address couldn't be determined of the machine running the
multicast communication server.  This is an artifact of a
client/server implementation of the multicast communication system.
X.TP 20
X[ENOENT]
X.I Mcast_getgroupbyname
was unable to find any information on
X.IR group .
X.TP 20
X[ENOMEM]
X.I Mcast_getgroupbyname
was unable to
X.I malloc
storage.
X.SH "SEE ALSO"
X.IR mcast (4),
X.IR mcast_getgroupbyname (3),
X.IR mc_fcntl (2),
X.IR mc_socket (2)
X.SH STANDARDS
There are no current standards that address multicast communication.
The software described in this manual page is experimental and subject
to change at any time.
END_OF_FILE
if test 5587 -ne `wc -c <'man/mcast_sopen.3'`; then
    echo shar: \"'man/mcast_sopen.3'\" unpacked with wrong size!
fi
# end of 'man/mcast_sopen.3'
fi
if test -f 'man/mcastd.8' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/mcastd.8'\"
else
echo shar: Extracting \"'man/mcastd.8'\" \(5500 characters\)
sed "s/^X//" >'man/mcastd.8' <<'END_OF_FILE'
X.\" Copyright (c) 1992 The Regents of the University of California.
X.\" All rights reserved.
X.\"
X.\" Redistribution and use in source and binary forms, with or without
X.\" modification, are permitted provided that the following conditions
X.\" are met:
X.\" 1. Redistributions of source code must retain the above copyright
X.\"    notice, this list of conditions and the following disclaimer.
X.\" 2. Redistributions in binary form must reproduce the above copyright
X.\"    notice, this list of conditions and the following disclaimer in the
X.\"    documentation and/or other materials provided with the distribution.
X.\" 3. All advertising materials mentioning features or use of this software
X.\"    must display the following acknowledgement:
X.\"    This product includes software developed by the University of
X.\"    California, Lawrence Livermore National Laboratory and its
X.\"    contributors.
X.\" 4. Neither the name of the University nor the names of its contributors
X.\"    may be used to endorse or promote products derived from this software
X.\"    without specific prior written permission.
X.\"
X.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X.\" SUCH DAMAGE.
X.\"
X.de Hd
X.ds Dt \\$4
X..
X.Hd $Header: /u0/casey/src/mcast/man/RCS/mcastd.8,v 1.1 92/10/16 18:23:09 casey Exp $
X.TH MCASTD 8 \*(Dt
X.SH NAME
mcastd \- multicast protocol server
X.SH SYNOPSIS
X.nf
X.ft B
mcastd [-d] [-l log-level] [-p port]
X.ft P
X.fi
X.SH DESCRIPTION
X.I Mcastd
is a server which simulates multicast communication for its clients.
Clients connect to
X.IR mcastd ,
subscribe to a
X.IR "multicast group" ,
and then send and receive messages on that group.
X.I Mcastd
is a precursor to an implementation of multicast communication that uses
real network multicast facilities.
X.PP
The following command line options are supported by
X.IR mcastd :
X.TP 5
X\fB\-d\fP
XEnables debug mode.
X.I Mcastd
will not disconnect from the tty.  All log messages will be sent to the
tty instead of the system logger.
X.TP 5
X\fB\-l\fP \fIlog\fP-\fIlevel\fP
Sets the system log level filter.  Only log messages at this or lower
levels will be logged.  The default log level is LOG_NOTICE (5 in most
systems).  This will cause messages noting normal, but significant
conditions to be logged.  Log level LOG_DEBUG (7 on most systems) will
cause copious amounts of messages to be logged detailing intimacies of
X.IR mcastd 's
operations.  LOG_DEBUG should only be used when debugging
X.I mcastd
since using it on a long term basis may well fill up a system's log
disk.
X.TP 5
X\fB\-p\fP \fIport\fP
Tells
X.I mcastd
to set up shop on the indicated
X.I port
instead of the default port.  (The default port is defined at installation
configuration.  In the software distribution it is defined to be
X.IR 8001 .
X.PP
A running
X.I mcastd
also responds to the following signals:
X.TP 5
SIGHUP
Causes
X.I mcastd
to reset.  All current connections are dropped and the server restarts.
X.TP 5
SIGTERM
Causes
X.I mcastd
to shutdown.  All current connections are dropped and the server exits.
X.PP
In operation, clients connect to
X.I mcastd
as they would any TCP based server.  Once connected they may send either
server control messages or data messages and receive data messages from
other clients (and sometimes themselves).  Service is terminated by either
the client or the server closing the connection.  The server should only
ever close its end of the connection if an error occurs or it is told to
reset or shutdown.
X.PP
The server control message format is described in
X.RI < netmcast / mcastd . h >
and the data message format is described in
X.RI < netmcast / mcast . h >.
However, under normal circumstances, no one should ever have to talk
directly to the server since there is a complete Berkeley socket-style
programming interface available.
X.SH COMPATIBILITY
This is experimental software.  It is not compatible with any other
multicast software.
X.SH PORTABILITY
Where possible, this software has been written to conform to ANSI C as
defined in
X.I "ANSI X3.159-1989"
and
POSIX 1003.1 as defined in
Unfortunately there are no standards available yet for networking APIs.
Where we were forced to step beyond the ANSI C and POSIX 1003.1 standards,
we chose to use the BSD
X.RI ( "Berkeley Software Distribution" )
definitions.  As such, it depends on the BSD
X.I socket
facilities, I/O control mechanisms, etc.
X.I Mcastd
also depends on
X.IR select (2)
to handle multiplexing multiple client connections.
X.IR "IEEE Std 1003.1-1990" .
X.SH "RETURN VALUES"
X.SH ERRORS
X.SH "SEE ALSO"
X.IR mcast (4),
X.IR mc_socket (2),
X.IR select (2),
X.IR socket (2),
X.IR syslog (3),
X.IR syslogd (8)
X.SH STANDARDS
There are no current standards that address multicast communication.
The software described in this manual page is experimental and subject
to change at any time.
END_OF_FILE
if test 5500 -ne `wc -c <'man/mcastd.8'`; then
    echo shar: \"'man/mcastd.8'\" unpacked with wrong size!
fi
# end of 'man/mcastd.8'
fi
if test -f 'test/mc_ping.c' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'test/mc_ping.c'\"
else
echo shar: Extracting \"'test/mc_ping.c'\" \(5914 characters\)
sed "s/^X//" >'test/mc_ping.c' <<'END_OF_FILE'
X/*
X * $Header: /u0/casey/src/mcast/test/RCS/mc_ping.c,v 1.4 93/01/16 20:18:39 casey Exp $
X */
X
X/*
X * Copyright (c) 1992 The Regents of the University of California.
X * All rights reserved.
X *
X * Redistribution and use in source and binary forms, with or without
X * modification, are permitted provided that the following conditions
X * are met:
X * 1. Redistributions of source code must retain the above copyright
X *    notice, this list of conditions and the following disclaimer.
X * 2. Redistributions in binary form must reproduce the above copyright
X *    notice, this list of conditions and the following disclaimer in the
X *    documentation and/or other materials provided with the distribution.
X * 3. All advertising materials mentioning features or use of this software
X *    must display the following acknowledgement:
X *    This product includes software developed by the University of
X *    California, Lawrence Livermore National Laboratory and its
X *    contributors.
X * 4. Neither the name of the University nor the names of its contributors
X *    may be used to endorse or promote products derived from this software
X *    without specific prior written permission.
X *
X * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
X * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
X * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
X * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
X * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
X * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
X * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
X * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
X * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
X * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
X * SUCH DAMAGE.
X */
X
X#ifndef lint
static char rcsid[] = "$Header: /u0/casey/src/mcast/test/RCS/mc_ping.c,v 1.4 93/01/16 20:18:39 casey Exp $";
static char copyright[] =
X    "Copyright (c) 1992 The Regents of the University of California.\n"
X    "All rights reserved.\n";
static char classification[] =
X    "Unclassified\n";
X#endif
X
X/*
X * Send messages to ourself on a specified multicast group and measure and
X * print the round trip time.
X */
X
X
X#include <errno.h>
X#include <fcntl.h>
X#include <stddef.h>
X#include <stdio.h>
X#include <stdlib.h>
X#include <string.h>
X#include <unistd.h>
X#include <sys/types.h>
X
X#include <sys/time.h>
X#include <sys/socket.h>
X#include <netmcast/mcast.h>
X
X
X/*
X * Arguments.
X */
char    *myname;            /* name we were invoked by */
int    header = 0;            /* print a header for every message */
int    debug = 0;            /* print lots of debug information */
int    size = 1024;            /* size of packets to ping with */
char    *group;                /* multicast group to listen to */
X
X
X/*
X * Local types.
X */
typedef struct mtag {
X    struct timeval    time;        /* time message was sent out */
X    unsigned long    seq;        /* sequence number of message */
X} mtag;
X
X
X/*
X * Local routines.
X */
void usage(void);            /* issue usage and exit with error */
void ping(void);            /* the ping routine */
X
X
main(int argc, char *argv[])
X{
X    int opt;
X    extern int getopt(int, char **, char *);
X    extern char *optarg;
X    extern int optind;
X
X    /*
X     * Parse any arguments ...
X     */
X    myname = argv[0];
X    while ((opt = getopt(argc, argv, "dhs:")) != EOF)
X        switch ((char)opt) {
X            case '?':
X            usage();
X            /*NOTREACHED*/
X            case 'd':
X            debug = 1;
X            break;
X            case 'h':
X            header = 1;
X            break;
X            case 's':
X            size = atoi(optarg);
X            break;
X        }
X    if (argc != optind+1) {
X        usage();
X        /*NOTREACHED*/
X    }
X    group = argv[optind];
X    if (size < sizeof(mtag)) {
X        fprintf(stderr, "%s: message size must be at least %u\n",
X            myname, sizeof(mtag));
X        size = sizeof(mtag);
X    }
X    ping();
X    exit(0);
X    /*NOTREACHED*/
X}
X
X
static void
ping(void)
X{
X    int s, n;
X    char *buf;
X    unsigned long seq;
X    fd_set readfds;
X    struct sockaddr_mcast addr;
X    struct timeval timeout;
X#ifndef _AIX
X    /*
X     * Patch around problem in IBM's AIX 3.2 where they define select
X     * with void pointers in <sys/select.h>.
X     */
X    extern int select(int, fd_set *, fd_set *, fd_set *, struct timeval *);
X#endif
X
X    buf = malloc((size_t)size);
X    if (buf == NULL) {
X        fprintf(stderr, "%s: unable to allocate %d size ping buffer!\n",
X            myname, size);
X        return;
X    }
X    (void)memset(buf, 0, size);
X    s = mcast_sopen(group, PF_MCAST, SOCK_STREAM, O_RDWR|MCO_LOOPBACK);
X    if (s < 0) {
X        perror("mcast_sopen");
X        exit(1);
X    }
X    n = sizeof(addr);
X    if (mc_getsockname(s, (struct sockaddr *)&addr, &n) < 0) {
X        perror("mc_getsockname");
X        exit(1);
X    }
X    seq = 0;
X    FD_ZERO(&readfds);
X    FD_SET(s, &readfds);
X    timeout.tv_sec = 1;
X    timeout.tv_usec = 0;
X    for (;;) {
X        int cc;
X
X        ((mtag *)buf)->seq = seq;
X        seq++;
X        (void)gettimeofday(&((mtag *)buf)->time, NULL);
X        cc = mc_sendto(s, buf, size, 0,
X                   (struct sockaddr *)&addr, sizeof(addr));
X        if (cc < 0) {
X            perror("write");
X            return;
X        }
X        if (cc < size) {
X            fprintf(stderr, "%s: write only wrote %d of %d!\n",
X                myname, cc, size);
X            return;
X        }
X        for (;;) {
X            int nfds;
X            fd_set fds;
X            struct timeval tN;
X            long delta;
X
X            fds = readfds;
X            nfds = select(s+1, &fds, NULL, NULL, &timeout);
X            if (nfds == 0)
X                break;
X            cc = mc_read(s, buf, size);
X            (void)gettimeofday(&tN, NULL);
X            if (cc == 0)
X                break;
X            if (cc < 0) {
X                perror("read");
X                return;
X            }
X            if (cc < size) {
X                fprintf(stderr, "%s: read only read %d of %d!\n",
X                    myname, cc, size);
X                return;
X            }
X            delta = (tN.tv_sec - ((mtag *)buf)->time.tv_sec) * 1000000
X                  + tN.tv_usec - ((mtag *)buf)->time.tv_usec;
X            printf("seq=%ld time=%ld us\n", ((mtag *)buf)->seq, delta);
X        }
X    }
X    /*NOTREACHED*/
X}
X
X
void
usage()
X    /*
X     * Issue usage message and exit with an error.
X     */
X{
X    fprintf(stderr, "usage: %s [-h] [-d] [-s size] group\n", myname);
X    exit(1);
X}
END_OF_FILE
if test 5914 -ne `wc -c <'test/mc_ping.c'`; then
    echo shar: \"'test/mc_ping.c'\" unpacked with wrong size!
fi
# end of 'test/mc_ping.c'
fi
echo shar: End of archive 3 \(of 4\).
cp /dev/null ark3isdone
MISSING=""
for I in 1 2 3 4 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 4 archives.
    rm -f ark[1-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0