.ds At AppleTalk
.TH zip 3
.SH NAME
.NA zip_getmyzone
.NA zip_getzonelist 
.NA zip_locallist
.TX
\*(At Zone Information Protocol (ZIP) interface
.SH SYNOPSIS
.\" .nf
.B "#include <netat/appletalk.h>"
.br
.B "#include <AppleTalk/at_proto.h>"
.br
.PP
.BI int\0zip_getmyzone(char\0* ifName ,
.BI at_nvestr_t\0* zone );
.PP
.BI int\0zip_getzonelist(char\0* ifName ,
.BI int\0* context ,
.BI u_char\0* zones ,
.BI int\0* size );
.PP
.BI int\0zip_getlocalzones(char\0* ifName ,
.BI int\0* context ,
.BI u_char\0* zones ,
.BI int\0* size );
.fi
.SH DESCRIPTION
The ZIP interface provides applications with access to the 
\*(At Zone Information Protocol operations.
.PP
The
.B zip_getmyzone
routine obtains the zone name for the local network.
The request is completed on the node itself.
.TP 8
.I ifName
A pointer to a character string containing the interface name, e.g. en0.
If ifName is a null pointer (ZIP_DEF_INTERFACE) the default
interface will be used.
.TP
.I zone 
A pointer to the zone name.
The zone string is defined by the following structure:
.sp
.nf
\s-1\f7typedef struct  at_nvestr {
        u_char  len;
        u_char  str[NBP_NVE_STR_SIZE];
} at_nvestr_t;\f1\s0
.fi
.TP
.I len 
The size of the string in bytes.
.TP
.I str
The zone name.
.PP
This routine returns 0 upon success, -1 on failure.
.PP
The
.B zip_getzonelist
routine
is used to obtain a complete list of all the zone names defined
in the internet.
This routine sends a ZIP request to a bridge for the list of zone names
in the internet.
The list is placed into the supplied buffer as concatenated
.B at_nvestr_t
structures.
.TP 8
.I ifName
A pointer to a character string containing the interface name, e.g. en0.
If ifName is a null pointer (ZIP_DEF_INTERFACE) the default
interface will be used.
.TP
.I context
*context should be set to ZIP_FIRST_ZONE for the first call.
The returned value may be used in the next call, unless it
is equal to ZIP_NO_MORE_ZONES.
.TP
.I zones
Pointer to the beginning of the "zones" buffer.
Zone data returned will be a sequence of at_nvestr_t
Pascal-style strings, as it comes back from the
ZIP_GETZONELIST request sent over ATP.
.TP
.I size
Length of the "zones" buffer; must be at least
(ATP_DATA_SIZE+1) bytes in length.
.PP
.B zip_getzonelist 
will return the zone count on success, and -1 on failure.
.PP
The
.B zip_getlocalzones
routine usage and behavior are the same as 
.B zip_getzonelist
except that it returns the list of zones on the local EtherTalk
cable rather than all the zones on the internet.
.SH DIAGNOSTICS
All routines return -1 on error
with a detailed error code stored in
.BR errno .
.TP 20
.B [EINVAL]
Invalid parameter (all).
.TP
.B [EIO]
An I/O error occurred.
.TP
.B [ENETUNREACH]
A bridge node could not be found to process the request (all).
.TP
.B [ENXIO]
An error occurred while sending a message to a device.
.PP
Routines also return any error codes returned by the underlying ATP,
DDP, or ALAP layers.
.SH WARNING
The returned zone strings are not null-terminated.
.SH "SEE ALSO"
.BR ddp (3),
.BR lap (3),
.BR atp (3),
.br
.IR "Inside AppleTalk" .